APL\3000 Information for Enthusiasts v1.0 2024-07-23 


This document provides some additional documentation for those that wish to use the APL\3000 
implementation available thru the SIMH simulator. It is primarily focused on the language and its 
implementation, and not on the use of the simulator. 


The APL\3000 Reference Manual is posted at bitsavers.org (Hewlett-Packard, 1976): 


http://www. bitsavers.org/pdf/hp/3000/mpell/32105- 
90002_APL3000_Reference_Manual_Nov1976.pdf 


Between 1976 and 1979, APL\3000 was updated several times. Unfortunately most of the associated detailed 
documentation has yet to surface on the Internet. Some details are identified across several documents: 


(The New APL/3000) 
httos://www.hpmuseum.net/pdf/ComputerSystemsNewsletter 1979 Mar15 45pages OCR.pdf 


(Programming for Performance in APL\3000) 
httos://www.softwarepreservation.org/projects/apl/Papers/ProgrammingForPerformance/view 


(Secure application environments in APL\3000) 
https://dl.acm.org/doi/10.1145/800136.804470 


(APL HP32105A.00.04 Date Code 1737, NOON105A.HP32105.SUPPORT) 
htto://www.bitsavers.org/pdf/hp/communicator/3000/14 3000 Oct77.pdf 


(APL 3000 HP32105A.01.00 Date Code 1906, NOON105A.HP32105.SUPPORT) 
https://www.hpmuseum.net/pdf/Communicator3000 Issue20 5951-6113 172pages Feb79.pdf 


(APL\3000 HP32105A.01.02 Date Code 1918, NOON105A.HP32105.SUPPORT) 
https://www.hpmuseum.net/pdf/Communicator3000 Issue21 5951-6113 164pages Oct79.pdf 


PRIVILEGE-USER MODE 


APL\3000 supports an undocumented privilege-user mode. Unlike other APL implementations, this does not 
provide access to any ‘admin’ functions but is primarily designed for testing and debugging of the APL 
implementation. When in this mode: 


1. Special implementor commands such as )MEM, ) TRACE, )CHECK, )DEBUG, )PRINTFOREST, 
)PRINTSCORE, )ZAP and ) BAM are available. 

2. Other right parenthesis commands function differently or are segmented, such as ) SHOW and 
)ERRORS. 

3. Allowed access to new functionality during development (not currently in use). 

4. Maintains the "break" capability. 


5. Place the user in DUMPVMEM instead of the system after a system about (e.g., APLABORT or an 
APLBT). 
6. APL displays the build number upon entering APL. 


One can turn on the PRIVUSER capability in one of two ways: 
1. In amore permanent manner, by having a local attribute (LOCATTR) of -422513551D (it used to be 1). 


This can be done for an account in the following manner (it recommended you do this on a new 
account): 


shello manager.sys 

[:newacct users, mgr; ...] 

[:altacct users; cap =...] 

:altacct users;locattr = -422513551 
shello mgr.users 

[:newuser aplpm; ...] 

:altuser aplpm;locattr=-422513551 
shello aplpm.users 


NOTE: You must reconnect ("hello') to the modified account after the "altacct"/"altuser" commands in 
ordered to pick up the change. 


2. For an APL session, by toggling the setting during a session by typing )<control-P> (two chars: 
parenthesis, then control-P). 


When enabled, ) BAM or )<CONTROL-P>, will turn off the setting for the session. It can be turned on again 
with )<control-P>. 


ERROR CHANGES 


A change was made to eliminate the ability to select between terse and verbose error messages using right 
parenthesis system commands. All error messages are now presented in terse format. The verbose format of 
an error message for the last error encountered can be displayed by viewing the value of JVMSG or (minus the 
line of the error and associated carat) by entering a question mark (?) as the only character on a line, followed 
by a carriage return. 


SYSTEM COMMANDS 


The system commands available in the current implementation of APL\3000 differs from that listed in the 
APL\3000 reference manual. Some commands are no longer available, others have been added, some are only 
available in privilege-user mode or perform differently in that mode. 


In 


APL\3000 | Privilege- 
System Reference user 
Command Manual | Command Notes 

)x Is used to enter EDIT mode with the function on the top 
of the state indicator, allowing for modification of the line 
where it is currently suspended. 

)BAM Yes Disables privilege-user mode. 

) CHECK Yes Sets the SYSCHECK flag to the opposite state. 

) CLEANUP Yes Attempts to clean up some internal problems with 
functions. 

) DEBUG Yes Puts the user into the debug procedure. 

)DEPTH Yes Is not implemented in later versions of APL. The system 
now allows recursive function calls to go as deep as 
possible. 

)ERRORS Prints out all possible error messages in both terse and 
verbose mode 

)ERRORS Yes In privilege-user mode, internal error code numbers are 
also displayed as well as a list sorted by these numbers. 

)EXIT Equivalent to )OFF. 

)FILES Yes Is replaced by ) LISTF (to avoid confusion with the new 
APL component files). 

) LANGUAGE Is optionally followed by 'APL' or 'APLGOL'. It is used to 
set the language mode switch to the specified language. 
If no mode is specified, it will list the current setting of 
the mode switch. 

)LISTF Replaces ) FILES. 

) LOCK Is followed by an APL or APLGOL function name and is 
used to lock that function. This is equivalent to the LOCK 
command in the editor. 

)ORIGIN Yes Does nothing except return a NONCE ERROR. 

)PRINTFOREST Yes Is optionally followed by a function name, line number, 
and statement number, and prints the D-trees and ECODE 
for the specified statement. If no function name is 
specified, the command appears to return a stub result. If 
no line number is specified, information for all lines and 
statements is displayed. If no statement number is 
specified, information for all statements is displayed. 

If the lines or statements have not been compiled into 
internal code, a statement for that line will be returned 
with "NO FOREST". 

) PRINTSCODE Yes Is followed by a function name, and prints the SCODE for 
the function. 

) SHOW Is optionally followed by a list of variables, and will print 


various information about the way each object is stored 
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In 
APL\3000 | Privilege- 
System Reference user 
Command Manual | Command Notes 
in the workspace. The details will vary based on the 
characteristics of the variable. 

) SHOW Yes In privilege-user mode, this command will also print out 
information about procedures and functions as well as 
some of the system versions (e.g., LJ) of these. 

)TERSE Yes Is no longer implemented in the current version. 

) TRACE Yes Sets the TRACE flag to the opposite state. When the 
TRACE flag is ON, then the D-trees and code generated 
will be printed when an APL line is processed is calculator 
mode or within a function. 

) UNLOCK Yes Does nothing except return a NONCE ERROR. 

) VERBOSE Yes Is no longer implemented in the current version. 

) VMEM Yes Puts the user into the DUMPVMEM procedure. 

)WIDTH Yes Does nothing except return a NONCE ERROR. 

) ZAP Yes Sets the ZAP flag to the opposite state. 

)ZIPPO Yes This command does nothing. 


Table 1 - Changed System Commands 


)ERRORS SYSTEM COMMAND 


Normally the ) ERRORS command will print out all possible terse and verbose error messages. 


) ERRORS 
CLASS SUBCL TERSE MESSAGE VERBOSE MESSAGE 
CLASS SYNTAX 
0 SYNTAX ERROR SYNTAX ERROR 

SYNTAX ERROR FUNCTION VALENCE CHANGED 
SYNTAX ERROR INCORRECT NUMERIC CONSTANT 
SYNTAX ERROR INCORRECT COMMENT 
SYNTAX ERROR NONEXISTENT CONTROL STRUCTURE 
SYNTAX ERROR DUPLICATE DEFAULT CASE 


VALUE ERROR VALUE ERROR 
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DOMAIN ERROR DOMAIN ERROR 

DOMAIN ERROR CANNOT DIVIDE BY O 
DOMAIN ERROR INTEGER OVERFLOW 

DOMAIN ERROR REAL OVERFLOW 

DOMAIN ERROR EXPONENT OVERFLOW 
DOMAIN ERROR EXPONENT UNDERFLOW 
DOMAIN ERROR NONEXISTENT ENVIRONMENT 


2 8 
2 9 
2 10 
2 11 
2 12 
2 13 
2 14 
2 15 
CLASS LENGTH 
3 1 
3 2 
CLASS RANK 
4 1 
4 2 
CLASS INDEX 
5 1 
CLASS DEFN 
6 1 
6 2 
6 3 
6 4 
6 5 
6 6 
6 7 
6 8 
6 9 
6 10 
6 14 
6 12 
6 13 
6 14 
CLASS ASSERT 
7 1 
CLASS FILE 
8 1 
8 2 
8 3 
FUNCTION 
8 4 
8 5 
8 6 
8 7 
8 8 
NAME 
8 9 
8 10 
8 14 
8 12 
8 13 


RESERVATION 


DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 


LENGTH ERROR 
LENGTH ERROR 


RANK 
RANK 


ERROR 
ERROR 


INDEX ERROR 


DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 


ASSERTION FAILED 


FILE 


ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 


ERROR 


WS LOCKED 


FILE 


FULL 


FILE NOT WS 
NO SPACE 


DEVICE NAME ERROR 


BAD WSID 
UNNAMED WS 


FILE RESERVATION ERROR 


BAD ARGUMENT 


APL FILE SYSTEM NOT AVAILABLE 
FILE FULL DATA PURGED 
UNRECOGNIZED RESERVATION 


ENVIRONMENT NOT ON STACK 

SV DOMAIN ERROR 

LOCKED FUNCTION ERROR 

FORMAT ERROR 

LEFT ARGUMENT MUST BE CHARACTER 
RIGHT ARGUMENT MUST BE INTEGER 
TIE NUMBER OUT OF RANGE 

PASS NUMBER OUT OF RANGE 


LENGTH ERROR 
SV LENGTH ERROR 


RANK ERROR 
SV RANK ERROR 


INDEX ERROR 


DUPLICATE LABEL 

DUPLICATE CASE LABEL 

CASE LABEL TOO BIG 

REAL CASE LABEL 

CASE RANGE TOO BIG 

CASE RANGE MUST BE INTEGER 
DUPLICATE NAME IN HEADER 
MISSING NAME 

TOO MANY NAMES 

ILLEGAL IN HEADER 

LOCAL LIST ERROR 

KEYWORD ' PROCEDURE ' MISSING 
FUNCTION ALREADY EXISTS 
CANNOT REPLACE PENDENT FUNCTION 


ASSERTION FAILED 


SHARED FILE ERROR 
INCORRECT PASSWORD SUPPLIED 
INSUFFICIENT FILE SPACE FOR 


FILE IS NOT AN APL WORKSPACE 

NO DISC SPACE AVAILABLE 

ILLEGAL DSLINE OR DEVICE FORMAT 
INCORRECT WORKSPACE NAME 

NOT SAVED - WORKSPACE HAS NO 


RESERVATION TOO SMALL FOR DATA 
EMPTY LEFT ARGUMENT 

APL FILE SYSTEM NOT AVAILABLE 
FILE FULL NO DATA IN COMPONENT 
NONNUMERICAL CHARACTER IN 


FILE RESERVATION ERROR 
FILE NAME ERROR 

FILE TIE QUOTA USED UP 
FILE TIE ERROR 
COMPONENT ERROR 

FILE ACCESS ERROR 

FILE NOT TIED 

NOT AN APL FILE 

NOT EXCLUSIVE TIED 
INVALID ACCESS MATRIX 
FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 


ACCOUNT OR GROUP NONEXISTENT 
ILLEGAL GROUP OR ACCOUNT 


COMPONENT ERROR 


USER PROCEDURE ERROR 
USER PROCEDURE ERROR 
USER PROCEDURE ERROR 


NONCE ERROR 


CONSTANT LIMIT 


COMMENT LIMIT 
NAME LIMIT 
ENVIRONMENT LIMIT 
SYSTEM LIMIT 


SYSTEM ERROR 
SYSTEM ERROR 


INTERRUPT 
INTERRUPT 
INTERRUPT 


8 14 
8 15 
8 16 
8 17 
8 18 
8 19 
8 20 
8 21 
8 22 
8 23 
8 24 
8 25 
8 26 
8 27 
8 28 
8 29 
CLASS USERPROC 
9 1 
9 2 
9 3 
CLASS NONCE 
10 1 
CLASS LIMIT 
14 1 
CONSTA 
NTS 
14 2 
14 3 
14 4 
14 5 
COMPUTATION 
CLASS SYSTEM 
12 1 
12 2 
CLASS INTERRUPT 
13 1 
13 2 
13 3 
13 4 


INTERRUPT 


RESERVATION OUT OF RANGE 

FILE NAME ERROR 

TWENTY FILES ALREADY TIED 
DUPLICATE TIE NUMBER 
COMPONENT NOT IN FILE 

ILLEGAL PASS OR ACCESS NUMBER 
INCORRECT TIE NUMBER 

FILE WAS NOT CREATED BY APL 
ILLEGAL SHARED FUNCTION 
ILLEGAL USER OR ACCESS NUMBER 
FILE SUBSYSTEM ERROR 

SYSTEM UNTIED FILE 

D FILE NOT PURGED 

ACCOUNT OR GROUP NONEXISTENT 
ILLEGAL GROUP OR ACCOUNT 
COMPONENT OUT OF RANGE 


USER PROCEDURE ERROR 
PROCEDURE DESCRIPTION ERROR 
RESULT DESCRIPTION ERROR 


NOT IMPLEMENTED 


STRING CONTAINS MORE THAN 8188 


TOO MANY COMMENTS 

NAME LIMIT 

ENVIRONMENT LIMIT EXHAUSTED 
SYSTEM CANNOT PERFORM THIS 


SYSTEM ERROR 
UNEXPECTED FILE ERROR 


SOFT INTERRUPT 
HARD INTERRUPT 
INTERRUPT - WS NOT LOADED 
INTERRUPT - WS NOT SAVED 


When in privileged-user mode, the ) ERRORS command will print out additional information. 
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TERSE MESSAGE 


SYSTEM LIMIT 
SYSTEM LIMIT 
SYNTAX ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DEFN ERROR 

DEFN ERROR 

SYNTAX ERROR 
SYNTAX ERROR 


DEFN ERROR 
DEFN ERROR 
DEFN ERROR 
DEFN ERROR 


SYNTAX ERROR 
DEFN ERROR 
DEFN ERROR 
DEFN ERROR 
DEFN ERROR 
DEFN ERROR 
SYNTAX ERROR 


DEFN ERROR 


DEFN ERROR 


CONSTANT LIMIT 


COMMENT LIMIT 


DEFN ERROR 


NAME LIMIT 
SYNTAX ERROR 
DEPTH ERROR 
DOMAIN ERROR 
SYSTEM LIMIT 
INDEX ERROR 
SYSTEM LIMIT 
LENGTH ERROR 
RANK ERROR 
SYSTEM LIMIT 
SYSTEM LIMIT 
SYSTEM ERROR 
VALUE ERROR 
WS FULL 


VERBOSE MESSAGE 

SYSTEM LIMIT 

SYSTEM LIMIT 

INCORRECT COMMENT 
EXPONENT OVERFLOW 
EXPONENT UNDERFLOW 
DUPLICATE LABEL 
DUPLICATE NAME IN HEADER 
SYNTAX ERROR 

NONEXISTENT CONTROL 


CASE LABEL TOO BIG 
REAL CASE LABEL 

CASE RANGE TOO BIG 
CASE RANGE MUST BE 


DUPLICATE DEFAULT CASE 
DUPLICATE CASE LABEL 
MISSING NAME 

TOO MANY NAMES 

ILLEGAL IN HEADER 
LOCAL LIST ERROR 
INCORRECT NUMERIC 


KEYWORD ' PROCEDURE ' 


FUNCTION ALREADY EXISTS 
STRING CONTAINS MORE THAN 


TOO MANY COMMENTS 
CANNOT REPLACE PENDENT 


NAME LIMIT 
SYNTAX ERROR 
FUNCTION CALLS TOO DEEP 
DOMAIN ERROR 
SYSTEM LIMIT 
INDEX ERROR 
SYSTEM LIMIT. 
LENGTH ERROR 
RANK ERROR 
SYSTEM LIMIT 
SYSTEM LIMIT 
SYSTEM ERROR 
VALUE ERROR 
WORKSPACE FULL 
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53 
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THIS COMPUTATION 


55 
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DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
SYSTEM LIMIT 
INTERRUPT 

NONCE ERROR 
SYNTAX ERROR 
INCORRECT COMMAND 
INTERRUPT 

BINDING ERROR 
DOMAIN ERROR 
DOMAIN ERROR 
ENVIRONMENT LIMIT 


ASSERTION FAILED 
SYSTEM LIMIT 


SYNTAX ERROR 

MUST BE APL OR APLGOL 
ILLEGAL LINE RANGE 

NUMBER TOO LARGE 

TOO MANY DECIMAL PLACES 
ILLEGAL NAME 

NUMBER TOO LARGE 

MISSING COLON 

MISSING START LINE 
MISSING LINE COUNT 
MISSING DELTA 

MISSING ASSIGNMENT 
MISSING DELTA VALUE 
ILLEGAL DELTA VALUE 

NO SUCH COMMAND 

CHANGE STRING NOT DEFINED 
FIND STRING NOT DEFINED 
PATTERN STRING NOT DEFINED 


NO LINE NUMBER ROOM 
NONCE ERROR 

LINE NOT FOUND 
STRING NOT FOUND 

WS FULL 

SYSTEM ERROR 

WS LOCKED 


SYSTEM LIMIT 
FILE NOT WS 


NO SPACE 
SYSTEM LIMIT 


CANNOT DIVIDE BY 0 
CANNOT DIVIDE BY 0 
INTEGER OVERFLOW 

REAL OVERFLOW 

SYSTEM LIMIT 

SOFT INTERRUPT 

NOT IMPLEMENTED 

FUNCTION VALENCE CHANGED 
INCORRECT COMMAND 

HARD INTERRUPT 

BINDING ERROR 
NONEXISTENT ENVIRONMENT 
ENVIRONMENT NOT ON STACK 
ENVIRONMENT LIMIT 


ASSERTION FAILED 
SYSTEM CANNOT PERFORM 


SYNTAX ERROR 

MUST BE APL OR APLGOL 
ILLEGAL LINE RANGE 
NUMBER TOO LARGE 

TOO MANY DECIMAL PLACES 
ILLEGAL NAME 

NUMBER TOO LARGE 
MISSING COLON 

MISSING START LINE 
MISSING LINE COUNT 
MISSING DELTA 

MISSING ASSIGNMENT 
MISSING DELTA VALUE 
ILLEGAL DELTA VALUE 

NO SUCH COMMAND 

CHANGE STRING NOT DEFINED 
FIND STRING NOT DEFINED 
PATTERN STRING NOT 


NO LINE NUMBER ROOM 
NOT IMPLEMENTED 

LINE NOT FOUND 

STRING NOT FOUND 
WORKSPACE FULL 
UNEXPECTED FILE ERROR 
INCORRECT PASSWORD 


SYSTEM LIMIT 
FILE IS NOT AN APL 


NO DISC SPACE AVAILABLE 
SYSTEM LIMIT 


84 8 

85 “4 

86 4 

87 4 

88 4 

89 4 

90 8 

NO NAME 

91 13 

92 13 

93 4 

94 4 
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96 
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99 

100 

101 

102 

RESERVATI 

103 

104 

105 

CHARACTER 

106 

INTEGER 

107 

108 

109 

110 

111 

112 

NUMBER 

113 8 

FOR FUNCTION 

114 8 
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APL 

116 8 
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BAD WSID 
SYSTEM LIMIT 
SYSTEM LIMIT 
SYSTEM LIMIT 
SYSTEM LIMIT 
SYSTEM LIMIT 
UNNAMED WS 


INTERRUPT 

INTERRUPT 

WILL NOT OVERLAY LINE 
INTERRUPT 

FILE ERROR 

USER PROCEDURE ERROR 
RANK ERROR 

LENGTH ERROR 

DOMAIN ERROR 

DOMAIN ERROR 

DOMAIN ERROR 


UNRECOGNIZED RESERVATION 


FILE RESERVATION ERROR 
FILE NAME ERROR 
DOMAIN ERROR 


DOMAIN ERROR 


DOMAIN ERROR 

DOMAIN ERROR 

FILE TIE QUOTA USED UP 
FILE TIE ERROR 
COMPONENT ERROR 

FILE ACCESS ERROR 


FILE FULL 


FILE NOT TIED 
NOT AN APL FILE 


NOT EXCLUSIVE TIED 
INVALID ACCESS MATRIX 


FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 


ACCOUNT OR GROUP NONEXISTENT 


ILLEGAL GROUP OR ACCOUNT 


COMPONENT ERROR 


INCORRECT WORKSPACE NAME 
SYSTEM LIMIT 

SYSTEM LIMIT 

SYSTEM LIMIT 

SYSTEM LIMIT 

SYSTEM LIMIT 

NOT SAVED - WORKSPACE HAS 


INTERRUPT - WS NOT LOADED 
INTERRUPT - WS NOT SAVED 
WILL NOT OVERLAY LINE 
INTERRUPT 

SHARED FILE ERROR 

USER PROCEDURE ERROR 

SV RANK ERROR 

SV LENGTH ERROR 

SV DOMAIN ERROR 

FORMAT ERROR 

LOCKED FUNCTION ERROR 
NONNUMERICAL CHARACTER IN 


RESERVATION OUT OF RANGE 
FILE NAME ERROR 
LEFT ARGUMENT MUST BE 


RIGHT ARGUMENT MUST BE 


TIE NUMBER OUT OF RANGE 
PASS NUMBER OUT OF RANGE 
TWENTY FILES ALREADY TIED 
DUPLICATE TIE NUMBER 
COMPONENT NOT IN FILE 
ILLEGAL PASS OR ACCESS 


INSUFFICIENT FILE SPACE 


INCORRECT TIE NUMBER 
FILE WAS NOT CREATED BY 


ILLEGAL SHARED FUNCTION 
ILLEGAL USER OR ACCESS 


FILE SUBSYSTEM ERROR 
SYSTEM UNTIED FILE 

D FILE NOT PURGED 
ACCOUNT OR GROUP 


ILLEGAL GROUP OR ACCOUNT 
COMPONENT OUT OF RANGE 


124 8 9 FILE RESERVATION ERROR RESERVATION TOO SMALL FOR 
DATA 


125 8 10 BAD ARGUMENT EMPTY LEFT ARGUMENT 

126 8 11 APL FILE SYSTEM NOT AVAILABLE APL FILE SYSTEM NOT 
AVAILABLE 

127 8 12 FILE FULL DATA PURGED FILE FULL NO DATA IN 
COMPONENT 

128 8 6 DEVICE NAME ERROR ILLEGAL DSLINE OR DEVICE 
FORMA 

T 

129 9 2 USER PROCEDURE ERROR PROCEDURE DESCRIPTION 
ERROR 

130 9 3 USER PROCEDURE ERROR RESULT DESCRIPTION ERROR 
ERROR CLASS SUBCL TERSE MESSAGE VERBOSE MESSAGE 

CLASS SYNTAX 

7 26 0 1 SYNTAX ERROR SYNTAX ERROR 

46 0 2 SYNTAX ERROR FUNCTION VALENCE CHANGED 
19 0 3 SYNTAX ERROR INCORRECT NUMERIC 
CONSTANT 

2 0 4 SYNTAX ERROR INCORRECT COMMENT 

8 0 5 SYNTAX ERROR NONEXISTENT CONTROL 
STRUCTURE 

13 0 6 SYNTAX ERROR DUPLICATE DEFAULT CASE 
CLASS VALUE 

37 1 1 VALUE ERROR VALUE ERROR 

CLASS DOMAIN 

28 2 1 DOMAIN ERROR DOMAIN ERROR 

39 40 2 2 DOMAIN ERROR CANNOT DIVIDE BY O 

41 2 3 DOMAIN ERROR INTEGER OVERFLOW 

42 2 4 DOMAIN ERROR REAL OVERFLOW 

3 2 5 DOMAIN ERROR EXPONENT OVERFLOW 

4 2 6 DOMAIN ERROR EXPONENT UNDERFLOW 

50 2 7 DOMAIN ERROR NONEXISTENT ENVIRONMENT 
51 2 8 DOMAIN ERROR ENVIRONMENT NOT ON STACK 
99 2 9 DOMAIN ERROR SV DOMAIN ERROR 

101 2 10 DOMAIN ERROR LOCKED FUNCTION ERROR 
100 2 14 DOMAIN ERROR FORMAT ERROR 

105 2 12 DOMAIN ERROR LEFT ARGUMENT MUST BE 
CHARACTER 

106 2 13 DOMAIN ERROR RIGHT ARGUMENT MUST BE 
INTEGER 

107 2 14 DOMAIN ERROR TIE NUMBER OUT OF RANGE 
108 2 15 DOMAIN ERROR PASS NUMBER OUT OF RANGE 
CLASS LENGTH 

32 3 1 LENGTH ERROR LENGTH ERROR 

98 3 2 LENGTH ERROR SV LENGTH ERROR 

CLASS RANK 


33 4 1 RANK ERROR RANK ERROR 


10 


97 4 
CLASS INDEX 
30 5 
CLASS DEFN 
5 6 
14 6 
9 6 
10 6 
14 6 
12 6 
INTEGER 

6 6 
15 6 
16 6 
17 6 
18 6 
20 6 
MISSING 

21 6 
24 6 
FUNCTION 
CLASS ASSERT 
53 7 
CLASS FILE 
95 8 
719 8 
SUPPLIED 
113 8 
FOR FUNCTION 
81 8 
WORKSPACE 
82 8 
128 8 
FORMAT 

84 8 
90 8 
NO NAME 
124 8 
DATA 

125 8 
126 8 
AVAILABLE 
127 8 
COMPONENT 
102 8 
RESERVATION 
103 8 
104 8 
109 8 
110 8 


RANK 


INDEX ERROR 


DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 


DEFN 
DEFN 
DEFN 
DEFN 
DEFN 
DEFN 


DEFN 
DEFN 


ASSERTION FAILED 


FILE 


ERROR 


ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 


ERROR 
ERROR 
ERROR 
ERROR 
ERROR 
ERROR 


ERROR 
ERROR 


ERROR 


WS LOCKED 


FILE 


FILE NOT WS 


FULL 


NO SPACE 


DEVICE NAME ERROR 


BAD WSID 
UNNAMED WS 


FILE RESERVATION ERROR 


BAD ARGUMENT 
APL FILE SYSTEM NOT AVAILABLE 


FILE FULL DATA PURGED 
UNRECOGNIZED RESERVATION 
FILE RESERVATION ERROR 
FILE NAME ERROR 


FILE TIE QUOTA USED UP 
FILE TIE ERROR 


SV RANK ERROR 
INDEX ERROR 


DUPLICATE LABEL 
DUPLICATE CASE LABEL 
CASE LABEL TOO BIG 
REAL CASE LABEL 

CASE RANGE TOO BIG 
CASE RANGE MUST BE 


DUPLICATE NAME IN HEADER 
MISSING NAME 

TOO MANY NAMES 

ILLEGAL IN HEADER 

LOCAL LIST ERROR 

KEYWORD ' PROCEDURE ' 
FUNCTION ALREADY EXISTS 
CANNOT REPLACE PENDENT 
ASSERTION FAILED 


SHARED FILE ERROR 
INCORRECT PASSWORD 


INSUFFICIENT FILE SPACE 


FILE IS NOT AN APL 


NO DISC SPACE AVAILABLE 
ILLEGAL DSLINE OR DEVICE 


INCORRECT WORKSPACE NAME 
NOT SAVED - WORKSPACE HAS 


RESERVATION TOO SMALL FOR 


EMPTY LEFT ARGUMENT 
APL FILE SYSTEM NOT 


FILE FULL NO DATA IN 
NONNUMERICAL CHARACTER IN 
RESERVATION OUT OF RANGE 
FILE NAME ERROR 


TWENTY FILES ALREADY TIED 
DUPLICATE TIE NUMBER 


111 8 18 
112 8 19 
NUMBER 

144 8 20 
115 8 21 
APL 

116 8 22 
117 8 23 
NUMBER 

118 8 24 
119 8 25 
120 8 26 
121 8 27 
NONEXISTENT 

122 8 28 
123 8 29 
CLASS USERPROC 
96 9 1 
129 9 2 
ERROR 

130 9 3 
CLASS NONCE 
45 10 1 
CLASS LIMIT 

22 14 1 
8188 

CONSTANTS 

23 14 2 
25 14 3 
52 14 4 
EXHAUSTED 

54 14 5 


THIS COMPUTATION 
CLASS SYSTEM 


36 12 1 
78 12 2 
CLASS INTERRUPT 
yy 13 1 
48 13 2 
91 13 3 
92 13 4 


COMPONENT ERROR 
FILE ACCESS ERROR 


FILE NOT TIED 
NOT AN APL FILE 


NOT EXCLUSIVE TIED 
INVALID ACCESS MATRIX 


FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 
FILE SUBSYSTEM ERROR 


ACCOUNT OR GROUP NONEXISTENT 


ILLEGAL GROUP OR ACCOUNT 
COMPONENT ERROR 


USER PROCEDURE ERROR 
USER PROCEDURE ERROR 


USER PROCEDURE ERROR 
NONCE ERROR 
CONSTANT LIMIT 
COMMENT LIMIT 
NAME LIMIT 
ENVIRONMENT LIMIT 
SYSTEM LIMIT 
SYSTEM ERROR 
SYSTEM ERROR 
INTERRUPT 
INTERRUPT 


INTERRUPT 
INTERRUPT 
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COMPONENT NOT IN FILE 
ILLEGAL PASS OR ACCESS 


INCORRECT TIE NUMBER 
FILE WAS NOT CREATED BY 


ILLEGAL SHARED FUNCTION 
ILLEGAL USER OR ACCESS 


FILE SUBSYSTEM ERROR 
SYSTEM UNTIED FILE 

D FILE NOT PURGED 
ACCOUNT OR GROUP 


ILLEGAL GROUP OR ACCOUNT 
COMPONENT OUT OF RANGE 


USER PROCEDURE ERROR 
PROCEDURE DESCRIPTION 


RESULT DESCRIPTION ERROR 
NOT IMPLEMENTED 

STRING CONTAINS MORE THAN 
TOO MANY COMMENTS 

NAME LIMIT 

ENVIRONMENT LIMIT 

SYSTEM CANNOT PERFORM 
SYSTEM ERROR 

UNEXPECTED FILE ERROR 
SOFT INTERRUPT 

HARD INTERRUPT 


INTERRUPT - WS NOT LOADED 
INTERRUPT - WS NOT SAVED 


)SHOW SYSTEM COMMAND 
Normally the ) SHOW command is optionally followed by a list of variables, and will print various information 
about the way each object is stored in the workspace. The details will vary based on the characteristics of the 


variable. 


For example, given that A and D are variables and B is a function: 


) SHOW 


KKK A KKK 
TYPE: SCALAR 
REP: INTEGER 


KKK D KKK 


TYPE: MATRIX 
REP: BIT 
RANK: 2 
SHAPE: 2 2 
DEL: 2 1 
OFFSET: 0 


VIRTUAL ADDRESS OF DATA BLOCK: 000000 011336 
BLOCK LENGTH (WORDS) : 20 
NON-SHARED DATA BLOCK 


)SHOW B 
NOT SHOWN (FUNCTION): B 


When in privileged-user mode, the ) SHOW command will also print out information about procedures and 
functions as well as some of the system versions (e.g., []) of these. 


For example, given that A and D are variables and B is a function: 


) SHOW 


kkk A kkk (30) 
TYPE: SCALAR 
REP: INTEGER 


kKKK Boxee (29) 


TYPE: PROCEDURE 
RESULT: NO 
VALENCE: 0 

SYSTEM: APL 
LINES: 1 
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STORAGE: 43 

SCODE (000000 017202) 3 
CONST * NONE * 

COM *NONE * 

SFCB (000000 017604) 14 
FNHDR (000000 016700) 26 
TXT2LS * NONE * 

DEFBLK *NONE * 


kkk PD xee*k (34) 


TYPE: MATRIX 
REP: BIT 
RANK: 2 
SHAPE: 2 2 
DEL: 2 1 
OFFSET: 0 


VIRTUAL ADDRESS OF DATA BLOCK: 000000 011336 
BLOCK LENGTH (WORDS) : 20 
NON-SHARED DATA BLOCK 
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SYSTEM FUNCTIONS AND VARIABLES 


The tables below represent information relating to changes to system functions and variables followed by 


details associated with some of these. 


Name Description Syntax 
DAPPEND append component to file value [TAPPEND tienum,[passnum] 
DAPPENDR | file append with result result«value [TAPPEND tienum, [passnum] 
DAVAIL APL component file system OAVAIL anyvalue 

availability 
OcM calculator mode OcM 
DICONTINUE | continue CICONTINUE 
Licopy monadic/dyadic copy [namelist] DCOPY wsname 
LCR canonical representation 4 OCR 'function-name' 
DICREATE create anewcomponent file | fileid[;dsline-[device]][ size]' OCREATE 
tienum [,passnum] 
OCRL canonical representation of | num QCRL 'function-name' 
line 
[OICcScoM character string compact OCSCOM value 
Ocsp character string delimiter letter QCSD string 
OicsLoc character string locator string DCSLOC vector | matrix 
Uicsmop character string modifier stringt DCSMOD string2 
ODROP drop components from start | DROP tienum,number[,passnum] 
or end of file 
O1EMOD modify error handler [''lerror-classes] DEMOD ''l/error-handlers 
OEP external procedure link-up [01112] OEP 'name' 
DERASE erase component file 'fileid' DERASE tienum[,passnum] 
OFI format input OFI value 
OFILES list of APL component filesin | OFILES '' | groupname[.acctname] 
library 
OF MT commercial formatter pattern OFMT value 
OHHOLD hold/release component OHOLD tienumber(s) 
files for exclusive access 
OLIB list of workspaces inlibrary |QLIB '' | groupname[.acctname] 
OLISTF list all files OLISTF '' | groupname[.acctname ] 
DILOAD load workspace [110] OLOAD wsname 
OLock lock one or more functions OLOCK name[s] 
LINAMES return names of currently- CNAME S 
tied files 
CINUMS return tie numbers in use ONUMS 
OOF F off OOF F 
OIPCcopy monadic/dyadic pcopy [namelist] OPCOPY wsname 
OPRINT print on line printer [termtype] OPRINT value 
DORDAC read component-file access result<«[RDAC tienum[, passnum] 
matrix 
OROCI read component information | JRDCI tienum, component[,passnum] 
OREAD read component DREAD tienum, component[,passnum] 


15 


Name Description Syntax 
ORENAME rename component file 'fileid[:dslinename][ size]' DRENAME 
tienum[ ,oldpass[,newpass] ] 
DOREPLACE | file component replace value REPLACE tienum, component[,passnum] 
DRESIZE set maximum file size size QRESIZE tienum[,passnum] 
DORESUME resume function execution ORESUME 
ORP representation of variable ORP 'name' 
OSAVE save active workspace OSAVE wsname 
DCSAVEMARK | save mark for load OSAVEMARK 
OSIZE read file-size and OSIZE tienum[,passnum] 
component-range 
information 
OSTAC set component-file access value QSTAC tienum[, passnum] 
matrix 
OSTIE tie file for shared use 'fileid[;dsline-[device]]' OSTIE 
tienum[ ,passnum] 
OTIE tie file for exclusive use 'fileid[;:dsline-[device]]' OTIE 
tienum[ ,passnum] 
OUI user input OUI 
OUNTIE untie component file(s) OUNTIE tienumbers 
OVI verify input OVI value 
Over vector representation 4 OVR 'function-name' 
OXE execute OXE 
Table 2 - Changed System Functions 
Name Description Syntax 
OEMSG error message OEMSG 
OENUM error number OENUM 
DETEXT error handler text DETEXT 
OTO temporary system variableO | OTO[<value] 
OT 1 temporary system variable1 | OT1[<value] 
OT2 temporary system variable 2 | OT2[<value] 
OT3 temporary system variable 3 | OT3[<value] 
OT4+ temporary system variable 4 | OT4[<value] 
OT5 temporary system variableS | OT5[<value] 
OVMSG verbose error message OVMSG 


SYSTEM FUNCTIONS NOT IMPLEMENTED 


Table 3 - Changed System Variables 


The system has a couple of system functions which have placeholder code but only return a NONCE ERROR 
(when passed the correct arguments). This includes JCRL (canonical representation for a line) and [CSCOM 
(character string compress). 
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CCOUNT INFORMATION SYSTEM VARIABLE CHANGES 


The account information (JAI) system variable was changed in later versions of APL\3000 to align with IBM's 
APLSV. Instead of the original two positions, there are now four positions with the first and fourth being zero 
(although zero may be displayed in scientific notation). 


CONVERT SYSTEM FUNCTION CHANGES 


The convert (ICV) system function was changed in later versions of APL\3000 to support an additional 
conversion type. A left argument of 6 converts from characters to a Boolean vector representing the bit values 
of the characters. A left argument of 6 converts from a Boolean vector into characters. If the length of the 
Boolean vector is not a multiple of eight then the excess number of trailing elements are ignored. 


MONITOR VALUES SYSTEM FUNCTION CHANGES 


The monitor values (UMV) system function was changed in later versions of APL\3000 to return four items 
rather than two for each function line. In addition to the execution count and CPU time, it now returns the 
number of binding errors and page faults for each line. 


FUNCTION DISPLAY CHANGES 


The canonical representation (CR) and vector representation (UVR) system functions have been updated to 
allow for an optional left argument. When the left argument is 1, the output will be returned with line 
numbers included. 


VERIFYING INPUT AND FORMATTING INPUT 


The OVI (verify input) and OF I (format input) system functions work together to convert character data to 
numeric data. They are useful to verify that data entered by a user to a quote-quad input is numeric. 


OVI takes as its right argument a character vector and returns a Boolean vector as its result. The length of the 
result is equal to the number of non-blank character groups in the argument. For each group of non-blanks, 
the corresponding element of the result is set to 1 if and only if the non-blank characters form a valid APL 
numeric constant. 


OF I takes the same argument as OVI, returns a result of the same length as that of OVI, but the result is 
numeric. For each group of non-blank characters in the argument, the corresponding element of the result is 
set to O if the group does not form a valid numeric constant. Otherwise, it is set to the constant itself. 
Therefore, it is similar to the execute operator (¢) except that it does not return a syntax error for characters 
that cannot be converted to numbers. Also, the execute operator has a limit of 8188 numeric constants in its 
argument. FI and OVI are limited only by the maximum size of APL\3000 data items. 
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For example, if C is a character vector entered by the user, then (OVI C)/OFI C will return a numeric 
vector containing all the valid numeric constants in C. 


SPECIAL SYSTEM FUNCTIONS AND VARIABLES 


APL\3000 has several special system functions and variables used internally. These should not be used for end- 
user processing. They are only presented here for interest. They are often listed when ) TRACE is used. They 
often will not function from immediate execution mode due to various syntax checking or other limitations 
(e.g., expecting internal data structures). When they are callable from immediate execution mode, they may 
not function 100% as they would when called internally. 


OCM (calculator mode) is a placeholder function sometimes put on top of the internal stack when executing a 
string from immediate execution mode. 


OXE (execute) evaluates the APL expression given by the right argument in the environment given in the left 
environment. If no left argument is specified, the expression is evaluated in the current environment. 


QUT (user input) basically does 0) and then passes the input to the internal calling code. 


OTo, 0T1, OT2, 0T3,0T4 and OT5 are temporary variables used internally. 


SYSTEMS FUNCTIONS FOR SYSTEM COMMANDS 


APL\3000 did not initially have a way to perform a number of workspace and library related system commands 
such as )LOAD, ) SAVE and )COPY in functions. This was changed in a later release thru the addition of the 
system functions listed below. 


OICONTINUE is similar to ) CONTINUE, which terminates APL after saving the active workspace under the 
name CONTINUE. 


OCOPY is similar to ) COPY, which copies all, or a list of objects (as specified by the optional left argument), 
from a specified workspace (as specified in the right argument) into the active workspace. 


OLIB is similar to ) LIB, returning in a matrix the names of the workspaces, in alphabetical order, that exist 
for a the specified library. Using a null character string (e.g., ' ') returns the information for the current user. 


OLISTF is similar to ) LISTF, returning in a matrix the names of the MPE files, in alphabetical order, that are 
associated with a specified group and account. Using a null character string (e.g., ' ') returns the information 
for the current user. 


OLOAD is similar to ) LOAD, which loads a copy of the saved workspace into the active workspace. There is 


one additional feature with DLOAD which is controlled with an optional left argument. If the optional left 
argument is 1, operation of the function that was executing if, and when, the workspace was saved using 
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OSAVE, continues. If )LOAD, or QLOAD without this option, is executed, this is not done and ULX processing 
occurs. For example: 


4 OCR 'SAMPLE' 


[0] SAMPLE 
[1] ‘BEFORE ' 
[2] OSAVE ‘EXAMPLE’ 
[3] 'AFTER' 
SAMPLE 
BEFORE 
01:47 11/01/72 
AFTER 


4 QILOAD ‘EXAMPLE’ 
01:47 11/01/72 
AFTER 


Use of the auto-resume option of LOAD is similar to the workspace being loaded and the resume (ORE SUME 
or )RESUME) operation being manually performed. Although in this later case, the save will be performed 
again. If resume is not performed, the stack will reflect that the function which performed the JSAVE system 
function is still on top of the stack of open functions. 


)LOAD EXAMPLE 
SAVED 01:47 11/01/72 
)SIV 
SAMPLE[2]* 
)RESUME 
01:48 11/01/72 
AFTER 


APL\3000 does this by placing on the stack a special system function (JSAVEMARK) that has zero lines and 
returns the saved timestamp value. This is then removed from the stack in the active workspace after the 
OSAVE has been performed. Upon a LOAD with auto-resume, the existence of JSAVEDMARK is checked to 
see if an auto-resume is to be performed. 


Note: APL is not properly checking the left argument to LOAD and may abort if passed a numeric value other 
than 0 or 1. 


OLOCK is similar to ) LOCK, which locks the functions or procedures which are named in the right argument, 
which is a vector or matrix of names. 


OPCOPY is similar to ) PCOPY, which copies all, or a list of objects (as specified by the optional left argument), 
from a specified workspace (as specified in the right argument) into the active workspace, except for those 
already existing in the active workspace. 


OSAVE is similar to ) SAVE, which saves the currently active workspace. There is one difference which is 
discussed under JLOAD. 


OOF F is similar to )OF F, which terminates APL without saving the active workspace. 
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ISSUEING EXTERNAL MPE PROCEDURE CALLS 

OEP (external procedure) issues a call to an external procedure which resides in a user provided SL. 
Limited checking is done to make sure the right argument is a legal MPE procedure name. 

The left argument is optionally a O, 4 or 2 (whose purpose is unknown). 


The handling of internal errors is not well implemented with this system function and it easily crashes APL. 


PRINTING 


The PRINT system function provides a quick and easy way to send APL data to the line printer or to a disc file 
from within an APL session or function. 


The optional left argument is a character vector representing the terminal type (i.e., termtype) of the receiving 
file or device (e.g., AJ, ASCII, BP, CDI, CP, DM, GST, HP). If not specified, the default value is ASCII. 
OPRINT takes as its right argument any APL variable or expression that has a value, formats it in the same 
manner as monadic format, and sends the result to a file whose formal designator is APLLP. This creates a 
spool file which is printed immediately. 


Suppose that you wanted each successive call to PRINT to append its results to a disc file. The following MPE 
commands, entered before invoking APL, or during the APL session using the )MPE system command or 
shared variables, would produce the desired results: 


:BUILD filename; REC=recsize,blockfactor,F,ASCII 
:FILE APLLP=filename, OLD; DEV=DISC; ACC=APPEND 


It is important to note that UPRINT will not return an error message even if you are attempting to append 
records past the end of the disc file. Before invoking UPRINT, it is advisable to set the value of OPW (print 
width) to the record size of the APLLP file. 


CHARACTER STRING SYSTEM FUNCTIONS 

In order to simplify and optimize the manipulation of character strings in APL\3000 and thereby increase its 
suitability in a commercial environment, three new system functions were implemented (JCSLOC, CSMOD 
and LCSD). 


OICSLOC - Character String Locator 


OICSLOC works as either a super dyadic iota or as a specialized * . =, based on the shape of the right 
argument. 
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The left argument of JCSLOC is a character scalar or vector representing the string to be found. 
The right argument is a character scalar, vector, or matrix. 


If the right argument is a scalar or vector, then the result of JCSLOC is an integer vector containing the 
starting indices of each occurrence of the left argument in the right argument. 


If the right argument is a matrix, then the result is an integer vector containing the row numbers for which the 
left argument appears, left-justified, in the right argument. 


In either case, an empty vector is returned if there are no occurrences of the left argument in the right 
argument. 
OICSMOD - Character String Modifier 


LICSMOD behaves like the 'Change' command in the editor. This system function takes as its right argument a 
character vector to be modified. The left argument is a character vector of the form: 


<delimiter> <string1> <delimiter> <string2> <delimiter>. 


Execution of JCSMOD causes all occurrences of string1 in the right argument to be replaced by string2. The 
delimiter may be any character. The modified character vector is returned as the result. 


For example: 

'/COW/BUFFALO/' QCSMOD 'HOW NOW, BROWN COW?' 
HOW NOW, BROWN BUFFALO? 

'*BE*x*' [JCSMOD 'TO BE OR NOT TO BE' 
TO OR NOT TO 


The second example demonstrates that JCSMOD can be used to delete occurrences of one string within 
another. 


OICSD - Character String Delimiter 

The LCSD system function creates a character matrix from a character vector. 

It takes a character vector as its right argument and a character scalar (the delimiter) as its left. The explicit 
result is a character matrix formed by scanning the right argument (left-to-right) and starting a new row of the 
result at each occurrence of the delimiter character. Any characters following the last occurrence of the 


delimiter will form the last row. 
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Consecutive, leading, or trailing delimiters cause empty rows to be formed. The delimiter characters do not 
appear in the result. If there are no occurrences of the delimiter in the right argument, then a one-row matrix 
is returned. 


DETERMINING STORAGE TYPE 


ORP (representation) returns the internal storage type associated with the right argument. 


1 - byte (character) 

2 - 16-bit integer 

3 - 32-bit integer or arithmetic progression vector (APV) 
4 - 32-bit real 

5 - 64-bit real 

6 - bit 


Note: The results of 2 and 4 should never be returned in newer versions of APL\3000. 


APPLICATION-CONTROLLED ERROR HANDLING 
Several functions and variable have been added to support application-controlled error handling. 


Note: The ability to configure APL to display verbose error messages in the immediately displayed error has 
been eliminated. 


A number of system variables have been added which report on APL errors. JEMSG (error message) returns a 
matrix of the terse form of the error message, the line that caused the error and the associated carat showing 
the position of the error. JVMSG (verbose error message) returns the same information with the exception 
that the first row contains the verbose form of the error message. JIENUM (error number) returns a numeric 
vector of the class and subclass numbers associated with the error (as shown in the results of ) ERROR ). For 
example: 


1+0 
DOMAIN ERROR 
1+0 
A 
OEMSG 
DOMAIN ERROR 
1+0 
A 
OVMSG 
CANNOT DIVIDE BY O 
1+0 
A 


OENUM 
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OEMOD establishes application-controlled error handling for error classes. It takes as a left argument a vector 
or matrix of error class(es) and as the right argument a vector or matrix of the functions or the associated 
immediate execution mode code (including functions) to perform when each associated error occurs. 

If the right argument is null, the additional error handling is canceled for the associated error class(es). 


If the left argument is not present, the right argument is assigned to all error classes. 


The error classes can be specified as either strings, or error codes, as reflected in the table below: 


ERROR ERROR 

CLASS CLASS 

STRING NUMBER 
ASSERT 7 
DEFN 6 
DOMAIN 2 
FILE 8 
INDEX 5 
INTERRUPT 13 
LENGTH 3 
LIMIT 14 
NONCE 10 
RANK 4 
SYNTAX 0 
SYSTEM 12 
USERPROC 9 
VALUE 1 


Typically, a function would be defined to address one or more error classes and JEMOD used to point to that 
function. The function would then perform the associated recovery or reporting function using the error 
information from the error-related system variables named above, clear the error handler, and resume the 
function using DRESUME. 


Associated with JEMOD is the system variable JETEXT, which contains the text that was specified and 
executed as a result of the JEMOD. 


APL COMPONENT FILE SYSTEM 


This is not to be confused with the workspaces used with the APL\3000 system. This is a file system used to 
store APL objects, and potentially share them with other users. It is modeled after Scientific Time Sharing 
Corporation's implementation. Unlike other APL implementations which kept 'F' as part of the associated 
system function and variable names, the APL\3000 implementation drops that letter from its associated names 
(e.g., using CREATE instead of OF CREATE). 


The APL\3000 file system is based on KSAM/3000 and can be manipulated by the various KSAM utilities such as 


KSAMUTIL and FCOPY. 
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Two MPE files are created when an APL component file is created, a data file and a key file. The data file has 
the same name as the APL file component name with the MPE file code of 8004. The key file is the APL file 
component name merged with the string '000001C' , using the formula 

((6Lpfilename)tfilename) ,6Lpfilename)+'0000001C' ), and with the MPE file code of 
KSAMK. Based on this, while an APL component file name can be up to eight characters in length, the first six 
must be unique among names for an APL component file for a given user. By default, the data files are created 
with the standard default lockword APLOOOOO, which must be used in MPE. If a passnum is used with the file in 
APL, then the MPE lockword is Apassnum (remember to use upper case A when entering this value). 


Note: If a file fails to open with error #192, the file was tied during a system crash. KSAMUTIL (e.g., RUN 
KSAMUTIL.PUB.SYS) should be used to repair the damaged file before it can be tied. 


Below are brief descriptions of the related system commands. 

OAVALL returns a 1 if KSAM, hence the APL component file system, is available. Otherwise a 0 is returned. 
LCICREATE creates a new APL component file and ties it to the session. 

OERASE purges an APL component file identified by a file ID and tie number. 

OTIE opens and ties an existing an existing APL component file for exclusive use. 


OISTIE opens and ties an existing an existing APL component file for shared use. This allows other user to 
open it shared and allows for file locking. 


OUNTTIE closes and unties a tied APL component file. 


ONAMES returns a matrix of tied files in the format name.group.account, and listed in the order the files were 
tied to the session. 


OINUMS returns a vector of tie numbers for all the tied files in the order the files were tied to the session. 


OSIZE returns a vector containing the number of the first component, the number of the next available 
component, the storage allocated to the file in bytes and the maximum allowed storage for the file (in bytes). 


OF ILES returns in a matrix the names of the APL component files, in alphabetical order, that are associated 
with a specified group and account. Using a null character string (e.g., ' ') returns the information for the 
current user. 


ORESIZE resizes the maximum allowed storage for a tied file. 


OIRDAC returns a character matrix containing the access matrix of the associated APL component file. If no 
access matrix has been set, an empty vector is returned. 


OSTAC sets the access matrix associated with a tied file. 
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The APL file component access control is implemented thru APL\3000 and is not part of the KSAM system. It is 
implemented as a matrix, stored in an APL component file, read during file operations and used to validate 
allowed file operations. 


The access matrix is character vector or matrix in which each line has two fields. The first field is user 
information in the form 'user|*.group|*.account|*' where an asterisk is a wildcard which matches all accounts 
of the specified category. The second field is a numeric value representing the file component functions, or 
privileges, allowed to be perform by the specified user. 


The access matrix entry is ignored if the current user is the creator of the APL component file. 


Valid privilege values in APL\3000 are ~ 4 thru 2047. In general, ~ 1 or #1 for the privilege value allows all 
access and zero allows none. Permission to use DSTIE (shared tie) is implicitly granted to any user who has 
any permission to use the file (i.e., has a non-zero privilege value). 


The privilege field is treated as a binary flag field, where each bit represents a function (or group of functions) 
that is allowed. While internally it is treated as a binary flag field, in APL it is an integer formed from the 
associated power of two integers which make up each flag. 


To form the permissions for a particular entry, one must select the numbers associated with the functions to 
be allowed and add them together. 


Privilege Allowed System 
Number Functions 
1 OREAD 
2 OTIE 
Ly DERASE 
8 OAPPEND 
16 OREPLACE 
32 LIDROP 
64 OHOLD 
128 ORENAME 
256 OSTAC ORDAC 
512 ORDCI 
1024 USIZe QRESIZE 


For example: 
Privilege Access Allowed 
1 OSTIE QREAD 
3 OSTIE QOTIE DREAD 
63 OSTIE QOTIE DREAD QERASE QAPPEND QREPLACE [DROP 


ORDCI returns a string containing the workspace storage (in bytes) required to hold a component, the account 
of the user who most recently did an append or replace, and the data and time of that action. 


OHOLD releases all currently held APL component files for a user and then puts a hold on the files represented 
by the specified tie number(s). All file holds can be released by specifying DHOLD 10. They are also released 
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when a user returns to immediate execution mode. This means you cannot experiment with QHOLD in 
immediate execution mode. JHOLD may do nothing on some single-user versions of APL\3000. 


ORENAME renames a tied APL component file. The file remains tied to the session. 

OIAPPEND creates a new component in a tied file with a value equal to the left argument. 
CIAPPENDR does the same as JAPPEND but returns an error if the function cannot be performed. 
OREAD returns the value of an existing component of a tied file. 

OREPLACE stores the value of the left argument in an existing component of a tied file. 


XIDROP drops the first (n) or last (-n) components from a tied file. 
FORMAT SYSTEM FUNCTION 


The format system function (FMT) included in newer releases allows for controlled formatting of input using a 
pattern. This was modeled after Scientific Time Sharing Corporation's format system function. As such, the 
material below is modified from associated documentation for that implementation. 


There are variations between the UFMT implementations in different APL systems including APL\3000. While 
an attempt has been made to account for those here, a complete analysis of the APL\3000 nuances has not 
been performed. Some variations in APL\3000 include: 


e Support for a base conversion phrase (Y) 

e Dropping of a leading zero for fractional numbers (e.g., .4 instead of 0.4) 

e No support for a zero replacement string modifier (O) 

e Support for many characters as delimiters between phrases, in addition to comma and space 

e Use of underbar (_) instead of 0 when displaying digits which are outside the internal precision of a 
formatted number 

e Different modifier per phrase restrictions 


OF MT is a dyadic system function with the following syntax: 

result < 'formatstring 'OFMT data 
The left argument, formatstring, is a character vector that specifies how you want the data to look. It contains 
specific formatting instructions that control the editing and display of the right argument, the data you want to 
format. 
The result of OFMT is always a character matrix. For example, the result of the expression: 

'I4' QFMT 987 


is a one-row, four-column character matrix containing the value' 987'. 


The number of rows in the matrix result is determined by the maximum number of matrix rows or vector 
elements in the data. The number of columns is determined by both the format string and the right argument. 
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The length of an edited line is limited only by the workspace storage required to hold the values. The value of 
OPW does not control the length of the line, and the value of DPW does not affect precision. 


Right Argument - The Data 
The right argument to DFMT is numeric or character scalar, vector or matrix (with a rank no more than 2). 


The system formats data expressions of different shapes as follows: 
e A matrix has each column formatted separately. 

e Avector is treated as a one-column matrix. 

e Ascalar is treated as a one-row, one-column matrix. 


If you want to display a vector horizontally, reshape it as a one-row matrix. 
Left Argument - The Format String 


The left argument to FMT is a character vector containing one or more format phrases. Individual format 
phrases are typically separated with commas. Other characters (e.g., space or semicolon) may also be used as 
long as they do not conflict with other parsing of the format string (e.g., are not mistaken for one of the phrase 
identifiers, modification identifiers or text delimiters). 


Each phrase is of the form 'rmLv' or 'rTtextT' where: 


ris an optional repeat factor 

m is an optional modifier 

Lis a single letter phrase identifier (e.g., A, E, F, G, I, T, X or y) 

v is a value associated with the phrase type (e.g., integer, number, pattern) 
Tis a text delimiter (e.g.,< > ¢ > " Q O) 

textis text 


This is all hard to grasp at once so the details of phrases are discussed in detail below. 

There are two classes of format phrases: 

e Editing format phrases edit data in the right argument; for example, the I format phrase displays numeric 
data in integer format. 

¢ Positioning and text format phrases change the appearance of the result without editing any data; for 
example, the T format phrase specifies tab stops for column placement. 

You can also use special parameters with many of the format phrases to specify the field width and precision of 

the image, and you can use modifiers to add special effects. 


Text Delimiters 


Text is placed in the left argument between pairs of valid delimiters. Any of the pairs of delimiters shown in the 
following list are valid. The closing delimiter must correspond to the opening one. 
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| Delimiters | Examples 
| < > <19__ > 
|< > cCR> 
OO O-0 
Oo 0 Hyeso 


You can use any of the delimiters as text characters within a format phrase; but one of them cannot be the 
closing delimiter. For example, to use the characters 


5>37 

as text in a format phrase, you could enclose them in different delimiters: 

c5>37> 

How the Format String is Processed 

The format string is scanned phrase-by-phrase from left to right. Editing format phrases are matched with 


columns of data, and positioning and text phrases are processed as they are encountered without reference to 
the data. 


You need not provide the same number of format phrases as columns of data in the right argument. The 
number of format phrases does not have to divide the number of columns of data evenly. If the format 
string contains an insufficient number of phrases to edit all of the data in the right argument, DFMT cycles 
through the format string repeatedly until all of the data has been edited. If the format string contains more 
phrases than are necessary to edit all the data, the trailing phrases are ignored. 


Spaces in the format string have no effect, except between text delimiters. 
How to Construct a Format String 
A format string comprises several parts: 
e Format phrases edit and position text and data. 
e Parameters are used with format phrases to give FMT detailed instructions. 
e Modifiers add special effects and decorations to edited data. 
For example, in the format string 
C113 
I is the format phrase telling UFMT to format numeric data as integers, 13 is the parameter to the I format 


phrase specifying a field width of 13 columns, and C is a modifier specifying that commas should separate 
every three digits in the data. 
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To construct a format string, determine a report width and the width of individual fields within the report. 
Then select appropriate format phrases for the corresponding data, and code the required parameters, 

such as field width and the number of digits to be displayed. You can also include modifiers and decorations for 
special effects. Add positioning phrases to the format string to control the location of 

fields. 


Simplify the coding of repeated format phrases or groups of format phrases by using repetition factors within 
parentheses. A repetition factor is a non-negative integer indicating the number of times to apply a phrase or a 


group of phrases. The default repetition factor is 1. 


You may find it helpful to store format strings as variables, especially if you will be using them with several 
different right arguments. 


Format Phrases 


The following format phrases are supported (they are displayed here without potential modifiers for 
simplicity): 


Phrase Type 

Aw Character 
Ew.s Exponential 
Fw.d Fixed point 
G<pattern > Pattern 

Iw Integer 

Tp or T Absolute tab 
Xp Relative tab 
Yw.b Base conversion 
<text> Text insertion 


The Editing Format Phrases 


The A, I, F, E, Gand Y format phrases place columns of data in the right argument into corresponding fields in 
the result. 
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A — Character Editing Phrase 

The A format phrase is the only phrase that edits only character data. 

The A phrase takes the form: Aw 

where w is the field width. The field width specifies the number of columns in the result to be occupied by the 
edited value. (Remember that a vector is treated as a one-column matrix and is formatted as a single column, 


unless it is reshaped to a one-row matrix.) 


'A1' OFMT 'SALT' 


odoTrmrn 


A character matrix in the data can contain several columns. In that case, you must specify a separate A format 
phrase for each column. 


'A1,A1,A1,A4' OFMT 1 4p'SALT' 
SALT 


Instead of typing the format phrase repeatedly, you can use a repetition factor to repeat the phrase. In the 
following example, a repetition factor of 4 is used. 


'4A1' QFMT 41 4p'SALT' 
SALT 


When the same format phrase is used for the entire right argument, as in the above example, you can omit the 
repetition factor. 


'A1' OFMT 1 4p'SALT' 
SALT 


If the field width is greater than 1, leading positions of the field are filled with blanks. 


WORDSQ < 3 3p'BOAURNSEQ' 
'A1,A2,A3' LFMT WORDSQ 


BO A 
UR N 
5. BQ 
'A2,A2,A2' UFMT WORDSQ 
BOA 
URN 
SEQ 


If you try to use an A format phrase to edit numeric data in the right argument, the result field is filled with 
stars (*). 
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'A6' OFMT 133 


KKKKKK 

Stars also result if you try to use an edit phrase other than A to edit character data. 
'I4' QFMT 'ABC' 

kKkKK* 


KKK 
KKK*K 


| — Integer Editing Phrase 
The I format phrase edits numeric data in integer format. The I phrase takes the form: Iw 


where wis the field width. An I format phrase displays numeric data as integers. Be sure to include space in 
the field width for negative signs in the result that correspond to negative values in the data. 


TABLE + 32 4 0.% 2 417 


TABLE 
1444444411 ~ , 3333333333 3 ~ 2187 
£25 5 2 128 
4 “4 “4 “4 

'3I14,16' OFMT TABLE 

0) 0 3 2187 
0 1 2 128 
4 a “4 
'I8' OFMT (3x4), 6€2 0.4 476.85912 
12 
600 
0 
477 


F — Fixed Point Editing Phrase 
The F format phrase edits numeric data in fixed point format. The F phrase takes the form: Fw.d 


where w is the field width and d is the number of decimal positions. The number of decimal positions specified 
must be between 0 and 32767, inclusive (although the later may cause an internal APL error). 


For example. the format phrase F9. 2 creates a field of nine positions, in which every value is formatted to two 
decimal places. Allow two positions in the field width for a possible negative sign and a decimal point. 


'F9.2' OFMT TABLE 


144 ~.33 “3.00 2187.00 
225 =, #50 2.00 128.00 
1.00 1.00 1.00 1.00 
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Unlike some other APL systems, for numbers between ~ 4 and 1, a zero is NOT placed to the left of the decimal 
point in the result. 


E — Exponential Editing Phrase 


The E format phrase edits numeric data in exponential (scientific notation) format. The E phrase takes the 
form: Ew.s 


where w is the field width and s is the exact number of significant figures in the non-exponent part of the 
result. For example, the format phrase E15.7 produces a field width of 15 with 7 significant digits. The 
number of significant digits specified must be between 1 and 16, inclusive. The width must be at least seven 
more than the number of significant digits to provide space for a negative sign, a decimal point, and a five- 
position exponent of the form E nnn. Additional width leaves visible space between columns. 


'€10.2' OFMT TABLE 1.1 


Pele “SE 1" G8c0E0: ~- 325263 
2sSEt <5¢0E-1 25060: ~de3b2 
1.0E0 1.0E0 1.0E0 1.0E0 


G — Pattern Editing Phrase 


The G format phrase edits numeric data according to a pattern or picture format. With this phrase, you can 
arbitrarily mix text characters and data in a formatted column by creating a pictorial template for the data. 
Special characters within the pattern indicate where to display digits in the data; other characters are displayed 
as they appear in the pattern. The G phrase takes the form: G<pattern > 


where pattern consists of the special characters 9 and Z, called digit selectors, along with other text characters 
to insert in the field. Use any valid pair of text delimiters to enclose the pattern. For example, to format a date 
with a G pattern, enter: 


'G<99/99/99>' [FMT 11887 
01/18/87 


The number of characters, including blanks, between the pattern delimiters determines the field width. The 
field is formatted with the exact number of characters and digits specified in the pattern. 


Data in the right argument is rounded to the nearest integer. Each digit of the integer is transferred to the field 
to replace a digit selector (9 or Z) in the pattern. A 9 in the pattern transfers the corresponding digit from the 
integer into the result. A Z suppresses leading and trailing zeros, transferring the corresponding digit only if the 
digit is nonzero or if it is between two transferred digits, as described below. 


Use the Z digit selector to omit leading or trailing zeros in the edited fields. If a Z corresponds to a zero in the 
integer, the zero is transferred only if digits on both sides are transferred; otherwise, the corresponding 
position in the field is unchanged. Since a 9 always transfers a digit to the result, a Z between two 9s acts as a 
9 digit selector. For example, G<Z9Z .99> is equivalent to G<Z99.99>. The following table compares the 
effects of using 9s and Zs as digit selectors: 
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Format Phrase 


G<Z99. 
G<Z99. 
G<ZZ9. 
G<ZZ9. 
G<ZZZ. 


99> 
9Z> 
9Z> 
ZZ> 
ZZ> 


Data 

2460 
2460 
2460 
2460 
2460 


1200 
1200 
1200 
1200 
1200 


Result 
0 24.60 12.00 00.00 
0 24.6 12.0 00.0 
0 24.6 12.0 0.0 
0 24.6 12 0 
0 24.6 12 


You must insert text characters or Z digit selectors in the pattern to display negative signs and decorations. 
Leading and trailing text characters always transfer directly to the result Text between digit selectors transfers 
only if digits to the right and to the left of the pattern text are transferred. Compare the appearance of zeros 


and commas in the next two examples. 


NUM 
ZEES 
NINES 


AAA AA FH 


+ 298738472 389487.987 387 0.35 

'G<$ ZZZ,2Z2Z,Z2Z29 AND NO CENTS>' 
'G<$ 999,999,999 AND NO CENTS>' 
ZEES FMT NUM 


< 


< 


298,738,472 AND NO 
389,488 AND NO 
387 AND NO 


0 AND NO 


NINES OFMT NUM 
298,738,472 AND NO 
000,389,488 AND NO 
000,000,387 AND NO 
000,000,000 AND NO 


CENTS 
CENTS 
CENTS 
CENTS 


CENTS 
CENTS 
CENTS 
CENTS 


You can use G formatting to produce visually effective reports when numbers are displayed in traditional 


patterns. 


EMPLO 
SSN 
TEL 
SALES 
SALARY 
FS 


ttetttt 


-FFFE SE 


7p ‘ABEL 
1p 298374562 298750385 384716453 273069857 
1p 4086729873 7187364782 8063948726 3138472637 
1p 567 309 4958 312 
1p 49800 50000 59500 41200 
G< 999-99-9999 >,G< (999) 999-9999>,16,G< ZZ,279>' 


GALOIS GAUSS ZORN 


EMPLO,FS OFMT SSN,TEL,SALES, SALARY 
ABEL 298-37-4562 
GALOIS 298-75-0385 
GAUSS 384-71-6453 
ZORN 273-06-9857 


(408) 
(718) 
(806) 
(313) 


672-9873 567 49,800 
736-4782 309 50,000 
394-8726 4958 59,500 
847-2637 312 41,200 


Although data values edited by a G format phrase are rounded to integers, fractional values in the data can be 
displayed by multiplying the data by the appropriate power of ten. In the following example, the data is 
multiplied by 100. 


MONEY « 1 4p 14.6 52 17 2.44 
'G< $99.99>' [FMT 100 x MONEY 
$14.60 $52.00 $17.00 $02.44 
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A better way to achieve the same effect is to prefix the G format phrase with the K scaling modifier. In the 
following example, the data is scaled by 102. 


'K2G< $99.99>' [FMT MONEY 
$14.60 $52.00 $17.00 $02.44 


Y — Base Number Conversion Editing Phrase 
The Y format phrase edits numeric data in integer format. The Y phrase takes the form: Yw.b 


where w is the field width and b is the numeric base that the numeric data is to be converted to. The base 
must bet a value from 2 to 16. Only the integer portion of the data is converted. 


To display the base 2 value for 8: 


'Y6.2' OFMT 8 
1000 


To display the base 8 value for 8: 


'Y6.8' QFMT 8 
10 


The Positioning and Text Format Phrases 


The positioning format phrases allow you to position fields without having to count individual positions. The 
positioning phrase specifies the column where the result of the next format phrase should begin: 


e The T phrase specifies the starting column relative to the left margin. 
e The X phrase specifies the starting column relative to the current position. 


The <text> format phrase inserts text directly into the result field. 

These three phrases do not edit data; they simply position it in the result. 

T — Absolute Tabbing Phrase 

The T phrase specifies absolute tabbing (jumping to a particular column). It takes the form: Tp or T 

where p is the column position (counting from the left margin) at which to format the next edited value. For 
example, T15 moves directly to position 15 regardless of the previous position. The first available position ona 
line is T1. 

If you use T without specifying the position, the next field is formatted to the right of the rightmost column of 


the result formatted thus far. 
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'I3,<:>,710,12' OFMT 2 2p1 63 2 49 
1: 63 
2: 49 


Using a T phrase before individual format phrases can make the format string easier to modify. The position of 
a field is clear and is independent of previous formatting instructions. 


X — Relative Tabbing Phrase 
The X phrase specifies relative tabbing, or positions to be skipped. It takes the form: Xp 


where p is the number of positions to be skipped from the present position before formatting the next field of 
the result. 


e If pis positive, p is the number of positions to be skipped to the right. 
e If p is negative, p is the number of positions to move left. 
e If pis zero, the phrase is ignored. 


Specify a negative value with a negative sign (X 12) or a minus sign (X-12). 


'T12,X 12,214,X4,14' OFMT 1 4p1 2 3 4 
7 a ee (ee 


<text> — Text Insertion Phrase 
The <text> phrase inserts the text between the delimiters into a line. The phrase takes the form: <text> 


where text is any combination of characters and spaces. All the text between the delimiters, including blanks, 
is inserted directly into the edited line. You can use any valid pair of text delimiters to enclose the 
text. 


DPT + 31p345 
REV « 3 1 p 344.50 89.74 250.13 
FS <« '<REVENUES FOR DEPT.>,I2,< ARE .. $>,F6.2' 
FS OFMT DPT,REV 

REVENUES FOR DEPT. 3 ARE .. $344.50 

REVENUES FOR DEPT. 4 ARE .. $ 89.74 

REVENUES FOR DEPT. 5 ARE .. $250.13 


Using Positioning and Text Phrases 


You can use the T and X format phrases to position fields without having to count individual spaces. In the 
format string: 


I5, X3, 25A1, T51, 4F7.2 
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the first floating point field begins in position 51, and if all four F phrases are used, the result is a matrix with 
78 (50 + 4x 7) columns. 


Positioning phrases may re-order data in the result. 


You can use text phrases to override previously formatted fields. The decimal point is replaced by a colon in 
this example. 


'F7.2, X 3, <:>, T' OFMT 1 4p10+0.15 x 41+14 
10:00 10:15 10:30 10:45 


You can use symbol substitution to achieve the same effect. 


A backward-pointing relative or absolute tab may cause a previously formatted field to be overlaid by a new 
field. This new field need not match the width or alignment of any previously formatted field. In this case, 
nonblank characters in the new field replace the corresponding characters in the old field. Blank characters in 
the new field that occur as the result of explicit mention in <text> phrases, G phrases, or certain modifiers also 
replace the corresponding characters in the old field. However, blanks used as fill characters do not replace 
any characters in the old field. 


In the following example, the background fill modifier R alters the normal blank background fill character. 


IOTA « 1 4p1 2 3 | 

'T12, T1, 214, T, I4' OFMT IOTA 
2. 3 1 4& 

'R<.>I12, Ti, 214, T, I4' OFMT IOTA 
(245.38s2.44 

'R<.>I12, Ti, 2R< >I4, T, I4' DFMT IOTA 
2, Bevat? (& 


In the last example, the blanks in the rightmost R modifier override previously formatted fields because they 
are text characters rather than fill characters. 


Repetition Factor 


A repetition factor can optionally precede most phrases. It determines how many times to use a single format 
phrase or a group of format phrases enclosed in parentheses. You can use it with any format phrase. The 
repetition factor precedes all other elements in the format phrase. For example, a repetition factor of 2 to the 
left of an editing format phrase causes that phrase to edit two successive columns from the data list. For 
example, F6.3,F6.3 isthe same as 2F6.3. 


A nonzero repetition factor to the left of a T phrase has no effect. For example, 3T5 is the same as T5 and 3T 
is the same as T. 


A nonzero repetition factor to the left of an X phrase repeats the specified skip. For example, 3X5 is the same 
as X15 and 3X 5isthesameas X 15. 
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A nonzero repetition factor to the left of a <text> phrase repeats that phrase. For example, 2<PAGO> is the 
same as <PAGOPAGO>. 


A zero repetition factor to the left of any phrase causes that phrase to be ignored. 
The default repetition factor is 1. 
Grouping Symbols 


Parentheses can be used in the left argument of [FMT to simplify the construction of repeated sets of format 
phrases and to limit further scanning of the format string when the data has been exhausted. A phrase may be 
enclosed by a single pair of parentheses, but nested parentheses are not allowed. 


Enclose the group of format phrases in parentheses and place the repetition factor to the left of the left 
parenthesis. 


12A1, 4(F10.2, I4) 
T15, 4&(X 4, I1) 


Without parentheses, you would have to specify the second format string in the preceding example as: 
115, X 4, I4, X 4, I1, X 4, IL, X 4, It 


A zero repetition factor to the left of a left parenthesis causes the phrases in the group to be ignored. 
If parentheses are used and no repetition factor is specified, 1 is assumed 


After all columns of data have been used, T, X, and <text> format phrases in the format string continue to be 
used until one of the following occurs: 


e an editing phrase (A, E, F, G, I or Y) with a nonzero repetition factor 

e the end of the format string 

e aright parenthesis with a repetition factor that has not been fully used 
e a left parenthesis. 


The following example demonstrates how to nest parentheses and how to use them to limit scanning of a 
format phrase when no more data is left to be edited. 


ADD <« 24%p12345 67 8 

ADD < (+/ADD) , ADD 

'I2, < = >,4(I1, (<+>))' OFMT ADD 
10 = 1+24+3+4 
26 = 5+6+7+8 
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Modifiers 


Modifiers add decorations and special effects to edited data. They are placed between the repetition factor 
and the format phrase. You can use any number of modifiers in any order, although there are some restrictions 
on the use of certain modifiers with certain phrases or other modifiers. 


Modifier Description Supported Phrases 
B Blank if zero F,1,Y 

C Comma insertion F,1,Y 

Ki Scale argument by 10*i E,F,G,1,Y 

L Left justify BLY 
M<text> Negative left decoration F,G,1,Y 
N<text> Negative right decoration F,G,1,Y 
P<text> Positive or zero left decoration F,G,1,Y 
Q<text> Positive or zero right decoration F,G,1,Y 
R<text> Background fill A,E, FG, |, Y 
S<symbolpairs> Symbol substitution F,G, 1, Y 

Z Zero fill F1,Y 


B -— Blank if Zero Modifier 
The B modifier leaves the field blank if the edited value is zero. 


EX « 65423.43 10 0.4 0 100 
'BF10.4' OFMT EX 
~65423.4 
~10.0 
eel 
(0 shows as a blank) 
100.0 


C-— Comma Modifier 
The C modifier inserts commas between each group of three digits in the integer part of the edited value. 
DATA < 2987309 3870.23 96874382 38E5 
'CI13' OFMT DATA 
2,987,309 
3,870 
96,874,382 
3,800,000 


Remember to provide extra positions in the field width for commas. 
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K — Scaling Modifier 


The K modifier scales (multiplies) a number before displaying it. It takes the form: Ki 


where j is a positive or negative integer. or zero. A negative value can be specified by a negative sign (K 2)ora 
minus sign (K-2). Each number to which the K modifier applies is multiplied by 10*/ before 


it is formatted. 


'F8.2,K1F10.2,K 2F10.2' OFMT 1 3p470.6 


470.60 4706.00 


4.74 


When used with a F, G, I or Y phrase, the K modifier controls how far the digits are shifted left or right of the 
decimal point in the result. With an E phrase, the K modifier adjusts the exponent in the result. 


The following table shows the use of scaling with decimal, exponential, and integer editing. 


Format Phrase 
F6.2 
K1F6.2 
K 2F6.2 


E9. 
K1E9. 
K2E9. 


FFE 


13 
K113 
kK 213 


Number 
24. 
24. 
24. 


24. 
24. 
24. 


24. 
24. 
24. 


60 
60 
60 


60 
60 
60 


60 
60 
60 


Result 
24.60 

246.00 

0.25 


2.460E1 
2.4602 
2.460E 1 


25 
246 
0 


Scaling is particularly useful when formatting numbers with the G phrase. 


Format Phrase 
G< 9.ZZ> 

K1G<Z9.ZZ> 
K2G<ZZ999> 
K2G<ZZ.99> 
K2G<ZZ.9Z> 


Number 
24. 
24. 
24. 
24. 
24. 


60 
60 
60 
60 
60 


Result 
0.25 
2.46 
2460 

24.60 

24.6 
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L — Left Justify Number Modifier 
The L modifier left-justifies the edited value in the result field. 


'LI9' OFMT 2*18 

2 

4 

8 

16 

32 

64 

128 

256 


When numbers with fixed decimal points or negative signs are left-justified, the alignment may be unusual. 


'LF10.2' OFMT 34.5 266 0.300 49.04 
34.50 
266.00 
0.30 
“49.04 


M — Negative Left Decoration Modifier 
The M modifier replaces negative signs with text you specify. It takes the form M<text> 


where text replaces the negative sign to the left of the result. Be sure to provide space in the field width for 
the decoration text.M< > is the default negative left decoration. 


In the following example, the M modifier replaces the APL negative sign (_) by the minus sign (-). 


EX « 65423.43 10 0.4 0 100 
'M<->F10.1' OFMT EX 
-65423.4 
-10.0 
-.4 
0.0 
100.0 


This kind of replacement can be helpful when you use a different type font to print a report. For example, since 
the APL negative sign (_) displays as a pound (#) in APL\3000 ASCII display, you could use M<-> to display 
negative values with a minus sign (-) in this situation. You can also use standard symbol substitution to solve 
similar problems. 
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N — Negative Right Decoration Modifier 


The N modifier places text you specify to the immediate right of an edited negative value. It takes the form 
N<text> 


where text represents the text. Be sure to provide space in the field width for the decoration text. 


_'N< MINUS>F20.2' OFMT EX 
65423.43 MINUS 


~410.00 MINUS 
~.40 MINUS 
0.00 

100.00 


P — Positive Left Decoration Modifier 


The P modifier places text you specify to the immediate left of an edited positive or zero value. It takes the 
form P<text> 


where text represents the text. Be sure to provide space in the field width for the decoration text. 


'Pp<+>F10.1' OFMT EX 
~65423.4 
~10.0 
~ sel 
+0.0 
+100.0 


Q - Positive Right Decoration Modifier 


The Q modifier places text you specify to the immediate right of an edited positive or zero value. It takes the 
form: Q <text> 


where text represents the text. Use this modifier with F, |, and G phrases. 
Be sure to provide space in the field width for the decoration text. 


'Q< DR>I10' OFMT EX 
~ 65423 
~ 410 
0 DR 
0 DR 
100 DR 


WhenM, N, P and Q modifiers are used with the G format phrase, the decoration text supersedes text 


characters in the pattern. The decoration text appears adjacent to leading or trailing nonzero digits in the 
result. 
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Therefore, the text phrases may not align. 


FMT « 'M<>N< CR>Q< DR>G<Z,ZZZ--->' 
FMT OFMT 123 120 242 0 100 1000 
123 CR 
12 DR- 
242 DR 


1 CR-- 
1. ORS H = 


R — Background Fill Modifier 


The R modifier fills the result field with text you specify in all positions not filled with the edited value. It takes 
the form R<text> 


where text represents the text. Starting at the left side of the field, text is repeated as many times as necessary 
to fill the field. Be sure to provide space in the field width for the decoration text. 


'R<o >110' OFMT EX 


0 0 65423 
© 0 0 o 10 
© 0 © o off 
© 0 © o of 
© 0 oe of 00 


'R<BACKGROUND>121' [FMT EX 
BACKGROUNDBACKG 65423 
BACKGROUNDBACKGROU 10 
BACKGROUNDBACKGROUNDO 
BACKGROUNDBACKGROUNDO 
BACKGROUNDBACKGROU100 


When used with the G format phrase, the R modifier is displayed only in positions not occupied by text 
characters or decorations. 


RDEC « 'R<*>G<$ ZZ2Z,22Z,229>' 
RDEC OFMT 23987458 38794 287 0 
«23,987,458 
kx***3B, 794 


KRKKKKKKKIBT 


AA FH 


KKK KKK KK KKO 
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You can use the R modifier to replace leading blanks in the result of an A format phrase with nonblank 
characters. 


'R<->A2' QFMT 3 3p'BOAURNSEQ' 
=B=0=A 
-U-R-N 
=SE>Q 
Unlike other implementations of APL, APL\3000 will fill in all blanks of the result based on the text. Including 
blanks that were in the original data source. Some other implementations only replace blanks caused by the 


phrase but not those in the original data source. 


However, the R modifier will not put the background text into a data position; rather, it will only fill in leading 
positions created by using a repetition factor. 


'R<*>A2' QFMT 1 8 p'JOHN DOE' 
kIT *OxH*xNxx*x*Dx*xOXKE 


In some other APL implementation the blank between JOHN and DOE is not filled in with a background star. 
xIJ*OxH*XNx *Dx*xOxE 

S — Standard Symbol Substitution Modifier 

The S modifier substitutes symbols of your choice for standard symbols used by [JFMT. Use the S modifier with 
F, G, and | format phrases. You can also use it with the G format phrase to free the digit selectors 9 and Z to 
serve as characters to be inserted in the result, and with an F or I format phrase to tailor other formatting 
effects to individual needs. S allows only a one-to-one substitution of symbols. 


The S modifier takes the form: S<symbolpairs> 


where the first symbol in each pair must be one of the symbols in the following table, and the second symbol is 
the temporary replacement for the first. 


This table contains a list of symbols that can be replaced using the S modifier. Applicable format phrases are 
shown in parentheses. 


Symbol | Purpose (Applicable Phrases) 
9 Digit selector (G) 
Z Digit selector, with leading and trailing zero suppression (G) 
* Field overflow fill character (F, G, I, Y) 

Decimal point (F) 


; C modifier insert character (F, I, Y) 
= Lack of significant digits fill character (F, G, I, Y) 
0 Z modifier fill character (F, I, Y) or leading-zero fill character 


from a 9 digit selector (G) 
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The following example shows how you can use the S modifier to display decimal numbers as clock times. 


'S<.:>F7.2' OFMT 1 4 p10+0.15 x 41+14 
10:00 10:15 10:30 10:45 


The substitution affects only the format phrase with the S modifier, as in the next example. 


'S<.V>F5.1, F9.3' OFMT 1 2 p 470.6 370.168 
470V6 370.168 


You can substitute for more than one symbol in a single format phrase. For example. symbol substitution can 
be used to follow European conventions. where periods rather than commas are used as number separators, 
and commas rather than periods are used as decimal points to mark the fractional part of a value. 


'S<.,,.>CF14.2' OFMT 1234567.89 
1.234.567,89 


The only substitutions permitted for symbols in the left argument to [FMT are those for the digit selectors 9 
and Z in the G format phrase. The other substitutions that are permitted affect symbols that JFMT places in 
the result. In the next example, the S modifier frees the digit selector 9 for use as a character in text. 


'S<9_>G<19__>' DFMT 64 57 72 54 
1964 
1957 
1972 
1954 


Use the S modifier to replace the stars that mark field overflow. 


'F5.2' OFMT o 100 1 


KKK 
3.14 
'S<*$>F5.2' OFMT o 100 1 


$$$$$ 
3.44 


The following uses of standard symbol substitution produce a DOMAIN ERROR: 


e An odd number of symbols appears between the delimiters; for example, S< . >. 

e The first symbol in a pair of symbols is not in the preceding table; for example, S<V . >. 

e More than one substitution is made for the same symbol in the same format phrase; for example, 
Ses tag 


e The same symbol is substituted for the digit selectors 9 and Z; for example, S<9_Z_>. 
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Z-— Zero Fill Modifier 
The Z modifier fills unused leading positions in the result field with zeros instead of blanks. 


'Z110' OFMT 3x1 23 4 5 
0000000003 
0000000006 
0000000009 
0000000012 
0000000015 


When the Z modifier is used with an editing phrase to format a negative value, the negative sign is left-justified 
in the result field. 


'715' OFMT 10 14 
~0001 
00000 
00001 


Combinations of Modifiers 


When the B modifier, and P or Q modifiers are used together, any data values that are zero appear as blanks, 
and the decoration text does not appear in the result field. 


_ 'BP<+ >15' OFMT 10 4 
1 


+ 1 


When the B and R modifiers are used together, any data values that are zero do not suppress the R fill text in 
the result field. 


'BR< NONE>F5.2' OFMT 10 4 
~4.00 
NONE 
1.00 


When the B and Z modifiers are used together, any data values that are zero appear as blanks in the result 
field. 


= 'BZI5' OFMT 10 1 
0001 


00001 
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When the L and Z modifiers are used together, the Z modifier has no effect. 


‘iris! BEM «4 0-4 


When the M and Z modifiers are used together, each negative data value appears with its negative sign 
replaced by the M decoration text. The decoration text is left-justified in the result field. 


'M<- >Z1I5' OFMT 101 
- 001 
00000 
00001 


When the P and Z modifiers are used together, each zero or positive data value appears with the P decoration 
text and is left-justified in the result field. 


'P<+ >Z15' OFMT 101 
~0001 
+ 000 
+ 001 


When the R modifier is used with one or more M, N, P, or Q modifiers, the decoration text overrides the 
background text for the portion of the field covered by the M, N, P, or Q modifier. 


FS<'R<*>M<->N<->P<+>Q<+>I15' 
FS OFMT 10 14 

xk-f- 

xx+O+ 

KK+ T+ 


Below are some examples of applications that use FMT with a combination of modifiers. The numeric array 
NUM is used in most of the examples. 


NUM 
1316026.715 755715.3407 4587093.116 
11586.9 2190044 .457 ~471009.5613 
6789137.817 0 9347189.744 
3836077.871 ~5195105.458 234.5 


Float Dollar Signs and Place Negative Values in Parentheses 


'C P<$> Q< > M<($> N<)> F19.2' DFMT NUM 


$1,316,026.72 $755,715.34 $4,587,093.12 

$11,586.90 $2,190,044 .46 ($471,009.56) 
$6,789,137.82 $0.00 $9,347,189.74 
$3,836,077.87 ($5,195,105.46) $234.50 
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Format Negative Values into Separate Columns and Omit Negative Signs 


'M<>N< > CI40' OFMT ,NUM 
1,316,027 
$907 LS 
4,587,093 
11,587 
2,190,044 
471,010 
6,789,138 
0 
9,347,190 
3,836,078 
5,195,105 
235 


Display Decorations Only 


BOOLEAN «00101 
'P<YES>R<NO >BI4, X-1, < >' OFMT BOOLEAN 


Stars in Result 


If stars appear in your result when you did not expect them, you probably used JJFMT incorrectly. Stars appear 
in the result when: 


e A formatted value is larger than the field width (often because you forgot to account for the width of 
decorations in the field width). 
e You tried to use an A format phrase to edit numeric data. 


e You tried to use a format phrase other than A to edit character data. 


You can avoid these conditions by using a larger field width, by scaling the data, or by using the correct format 
phrase for the data type. 


You can always substitute another symbol for the star by using the S modifier. 
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Unknown Digits in Result 


The precision of the result of OFMT is independent of the value of OPP. FMT displays up to 16 digits. A 
format phrase requesting more significant digits than are available in the internal representation uses an 
underbar for the missing digits (some other APL systems use 0). 


'F24.41' OFMT o 1€20 
3141592653589793 


In some other APL systems this would be displayed as 314159265358979330000.0. 
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Some Notes regarding the APL\3000 Reference Manual (11/1976 version): 


1. While the manual discusses the AJ terminal type option in two places, it fails to list it under the ) TERM 
command. 


2. The manual lists the 3-CHAR "ASCII" for O-underscore as "UN. It should be "UO. 


3. The manual does not document the current ASCII equivalent for left arrow ("assign"; «) which is the 
ASCII underscore (_). Whereas the ASCII equivalent for the APL underscore character (_) is the three- 
character ASCII equivalent "NL. 


The manual also does not document the current ASCII equivalent for the up arrow ("take"; t) which 
uses upper case 6 (*). Whereas the ASCII equivalent for the APL OR character (A) is the three-character 
ASCII equivalent "OR. 


This may be confusing since in most other cases, when there is an equivalent ASCII symbol for an APL 
symbol, they are used for the same purpose. 


ASCII was originally standardized in 1963. The 1963 version used the up-arrow for codepoint x5E and 
the left arrow for codepoint x5F. In alignment with an international standard (e.g., ISO/IEC 646) 
changes were made to ASCII in 1967 to use the caret for codepoint x5E and the underscore for 
codepoint x5F. 


Some early adopters of ASCII (e.g., DEC) held to the 1963 version of ASCII in their products, which is 
probably what is reflected in the manual. 


4. The manual incorrectly shows the three-character ASCII equivalent for jot (°, which is listed as null) as 
"UT (which is the three-character equivalent for underscore T). The proper three-character equivalent 
for jot is "JT. 


5. The three-character ASCII equivalent "SQ represents the APL\3000 character-error symbol. When 
certain three-character ASCII equivalent characters which are not valid functions (e.g., "CN) are entered 
in immediate execution mode, they are replaced in the error message with "SQ (instead of the original 
string). "SQ is also returned when a double quote precedes a string that would not result in a valid 
three-character ASCII equivalent. When enclosed in quotes, the system properly handles these 
characters. 


6. The manual fails to identify that the left arguments to CV for internal APL to external conversion 
should be negative values. 


7. The APL\3000 system was updated to include some extra characters as shown below. 


CHARACTER APL |3-CHAR| O-ORIGIN | APLENTRY 
NAME SYMBOL | "ASCII" | [AV INDEX CHARS 
CENT ¢ "CN 213 c | 
POUND £ "PD 214 iE. 
YEN ¥ "YE 212 Y= 
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However, there is a bug in APL\3000 in that the system is improperly translating these characters as 
shown in the examples below: 


"ICN! 
S¥E 
nye! 
"PD 
MDD! 
"CN 


If the last item in an APL expression is a string that is missing a closing quote, APL\3000 will act as if a 
closing quote was provided. For example 


A«'THIS 
A 
THIS 


. Various MPE file codes are associated with APL\3000 files. These include: 


File Code Type of File 

8000 Older APL workspace (version 00.05 and before) 

8001 Older APL temporary active-workspace file 

8002 Current APL workspace (version 01.00 and after; 
after 7-18-1977) 

8003 Current temporary active-workspace file 

8004 APL component data file 


10. The above material does not fully take into account support for DS Network Services (DS/3000) which 


was added to APL\3000 allowing for HP Computer-to-HP Computer communication. While the details 
for APL component file system usage is documented above, the details for )COPY, )PCOPY, )DROP, 

) SAVE and ) LOAD (as well as their system function counterparts) is missing. The syntax in those cases 
may be something like 


)command file[.group[.account]][/password][;dslline(#|l-)[ device] ] 


but not 100% sure. In the simulator these should not complete and indeed crash the simulator. 
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